Customer Cards

View a customer's loyalty card progress

Customer cards represent a customer’s instance of a loyalty card template. They track stamp progress, status, and wallet pass installation. Use these endpoints to view a customer’s enrolled loyalty cards and their current progress toward rewards.

index

GET /api/v1/accounts/:account_id/customers/:customer_id/customer_cards

List customer cards

Returns all loyalty cards enrolled for a specific customer, including stamp progress, status, wallet pass installation state, and wallet pass URLs (apple_wallet_url and google_wallet_url) that you can use to let customers add their loyalty card to Apple Wallet or Google Wallet from your own app or website.

Parameters

Name Type Required Description
account_id Must be a number. Required

Store (account) ID
customer_id Must be a number. Required

Customer ID

Error Codes

Code Description
401 Unauthorized – invalid or missing API token
404 Store or customer not found

Returns

Code: 200

An array of the customer's loyalty cards

Name Type Required Description
id Must be a Integer Required

Customer card ID
card_id Must be a Integer Required

Loyalty card template ID
card_name Must be a String Required

Name of the loyalty card
stamps_count Must be a Integer Required

Stamps collected so far
stamps_remaining Must be a Integer Required

Stamps still needed to complete the card
status Must be a String Required

Current state of the customer card
uuid Must be a String Required

Public identifier used in wallet pass URLs
progress_percentage Must be a Integer Required

Completion towards the next reward, 0 to 100
pass_installed Must be one of: true, false, 1, 0. Required

Whether the wallet pass has been installed
apple_wallet_url Must be a String Required

Link to add or view the pass in Apple Wallet
google_wallet_url Must be a String Required

Link to add or view the pass in Google Wallet
issued_at Must be a String Required

ISO 8601 timestamp the card was issued

(nil allowed)
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp

show

GET /api/v1/accounts/:account_id/customers/:customer_id/customer_cards/:id

Show a customer card

Returns detailed information about a specific customer card, including stamp progress, a list of rewards the customer has earned enough stamps to redeem, and wallet pass URLs (apple_wallet_url and google_wallet_url) for adding the card to Apple Wallet or Google Wallet.

Parameters

Name Type Required Description
account_id Must be a number. Required

Store (account) ID
customer_id Must be a number. Required

Customer ID
id Must be a number. Required

Customer card ID

Error Codes

Code Description
401 Unauthorized – invalid or missing API token
404 Store, customer, or customer card not found

Returns

Code: 200

A customer card, with its available rewards

Name Type Required Description
id Must be a Integer Required

Customer card ID
card_id Must be a Integer Required

Loyalty card template ID
card_name Must be a String Required

Name of the loyalty card
stamps_count Must be a Integer Required

Stamps collected so far
stamps_remaining Must be a Integer Required

Stamps still needed to complete the card
status Must be a String Required

Current state of the customer card
uuid Must be a String Required

Public identifier used in wallet pass URLs
progress_percentage Must be a Integer Required

Completion towards the next reward, 0 to 100
pass_installed Must be one of: true, false, 1, 0. Required

Whether the wallet pass has been installed
apple_wallet_url Must be a String Required

Link to add or view the pass in Apple Wallet
google_wallet_url Must be a String Required

Link to add or view the pass in Google Wallet
issued_at Must be a String Required

ISO 8601 timestamp the card was issued

(nil allowed)
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp
customer_id Must be a Integer Required

Owning customer ID
account_id Must be a Integer Required

Parent store ID
available_rewards Must be an Array of nested elements Required

Rewards this customer can redeem right now
available_rewards[id] Must be a Integer Required

Reward ID
available_rewards[name] Must be a String Required

Display name of the reward
available_rewards[description] Must be a String Required

Longer description of the reward

(nil allowed)
available_rewards[stamps_required] Must be a Integer Required

Stamps the reward costs

stamp

POST /api/v1/accounts/:account_id/customers/:customer_id/customer_cards/:id/stamp

Add stamps

Adds stamps to a customer’s loyalty card. Triggers ledger entries, wallet pass updates, and push notifications. Pass skip_notifications to stamp silently.

Parameters

Name Type Required Description
account_id Must be a number. Required

Store (account) ID
customer_id Must be a number. Required

Customer ID
id Must be a number. Required

Customer card ID
stamps Must be a number. Required

Number of stamps to add (e.g. 1, 3)
skip_notifications Must be one of: true, false, 1, 0. Optional

When true, stamp changes bypass notifications

Error Codes

Code Description
401 Unauthorized – invalid or missing API token
404 Store, customer, or customer card not found
422 Validation failed – check `errors` for details

Returns

Code: 200

The updated customer card, with its available rewards

Name Type Required Description
id Must be a Integer Required

Customer card ID
card_id Must be a Integer Required

Loyalty card template ID
card_name Must be a String Required

Name of the loyalty card
stamps_count Must be a Integer Required

Stamps collected so far
stamps_remaining Must be a Integer Required

Stamps still needed to complete the card
status Must be a String Required

Current state of the customer card
uuid Must be a String Required

Public identifier used in wallet pass URLs
progress_percentage Must be a Integer Required

Completion towards the next reward, 0 to 100
pass_installed Must be one of: true, false, 1, 0. Required

Whether the wallet pass has been installed
apple_wallet_url Must be a String Required

Link to add or view the pass in Apple Wallet
google_wallet_url Must be a String Required

Link to add or view the pass in Google Wallet
issued_at Must be a String Required

ISO 8601 timestamp the card was issued

(nil allowed)
created_at Must be a String Required

ISO 8601 creation timestamp
updated_at Must be a String Required

ISO 8601 last-update timestamp
customer_id Must be a Integer Required

Owning customer ID
account_id Must be a Integer Required

Parent store ID
available_rewards Must be an Array of nested elements Required

Rewards this customer can redeem right now
available_rewards[id] Must be a Integer Required

Reward ID
available_rewards[name] Must be a String Required

Display name of the reward
available_rewards[description] Must be a String Required

Longer description of the reward

(nil allowed)
available_rewards[stamps_required] Must be a Integer Required

Stamps the reward costs

redeem

POST /api/v1/accounts/:account_id/customers/:customer_id/customer_cards/:id/redeem

Redeem a reward

Redeems a reward for a customer, deducting the required stamps from their card. The customer must have enough stamps on this card to cover the reward’s cost. Triggers wallet pass updates and push notifications.

Parameters

Name Type Required Description
account_id Must be a number. Required

Store (account) ID
customer_id Must be a number. Required

Customer ID
id Must be a number. Required

Customer card ID
reward_id Must be a number. Required

Reward ID to redeem

Error Codes

Code Description
401 Unauthorized – invalid or missing API token
404 Store, customer, customer card, or reward not found
422 Redemption failed – not enough stamps or reward inactive

Returns

Code: 200

The redemption that was recorded

Name Type Required Description
success Must be one of: true, false, 1, 0. Required

True when the reward was redeemed
redemption Must be a Hash Required

What was redeemed
redemption[id] Must be a Integer Required

Redemption ID
redemption[reward_id] Must be a Integer Required

Reward that was redeemed
redemption[reward_name] Must be a String Required

Display name of the reward
redemption[stamps_spent] Must be a Integer Required

Stamps deducted from the card
redemption[stamps_remaining] Must be a Integer Required

Stamps left on the card afterwards
redemption[redeemed_at] Must be a String Required

ISO 8601 timestamp of the redemption